Very excited to see these being called out and updated!

My understanding is that a "suspense enabled framework" is a framework that wraps these features that activates a suspense boundaries . If that is true could we specifically call it out what suspense enabled means?

Maybe this? 021f94d

This line is out of date because of yours and @rickhanlonii great work on the use() docs.

Nice catch!!! Updating!

I opened issue #8490 about the need for a caveat regarding React's batching of Suspense content, which has resulted in several issues in the React repo that can be solved with documentation. If we can add it to this pr, it would be great. I am thinking something like this:

@eps1lon can you verify this number?

d34d3ce added here but happy to revert

React waits at least 300ms before replacing the fallback with new content. That's different to blocking display of a fallback which only happens during updates in Transitions.

The idea is that filling in content more often leads to a "popcorn" effect. Imagine a 10x10 grid where each cell pops in 50ms intervals instead of doing 2-3 reveals including multiple cells. 300ms is just a heuristic that allows batching reveal of multiple boundaries.

Simplified 16fa091 and added link 54958a7

not quite sure i understood what you wanted though

I like your caveat much better than my suggestion (great job!). But I feel like it implies that suspense will always show a fallback.

My understanding is that
0ms to ~10 ms - no fallback; suspense just renders children
11ms to ~300ms - batch at call; all render all together after 300ms
~310ms+ render in 300ms windows (not sure about this one)

This is figuring out an ideal rendering schedule; it is very impressive work by the React team, but is a little hard to explain. I hope I am not derailing the goals of this pr.

Would need @eps1lon here to confirm and define what docs should include

The throttling heuristic always blocks new boundary reveals counting from the last reveal. It has no impact on whether we display a fallback or not which is decided independently (always show fallback on mount, stay on content on update).

The very first boundary React will always reveal asap. If the boundary suspended, React shows a fallback immediately. When the boundary unsuspends, React will not reveal the boundaries content before 300ms have elapsed since the last reveal.

Throttling is surfaced in the performance tracks added by React.

Consider this example (using https://codesandbox.io/p/sandbox/quiet-http-yplr4n):

function App({ p1, p2, p3 }) {
  return (
    <main>
      <h1>document</h1>
      <p>shell </p>
      <Suspense fallback="Loading lvl 1">
        <p>boundary lvl</p>
        <Suspender promise={p1} />
        <Suspense fallback="Loading lvl 2">
          <p>boundary lvl2</p>
          <Suspender promise={p2} />
          <Suspense fallback="Loading lvl 3">
            <p>boundary lvl3</p>
            <Suspender promise={p3} />
          </Suspense>
        </Suspense>
      </Suspense>
    </main>
  );
}

All Promises start at the same time as we can commit shell (which doesn't suspend and is committed instantly).

p1 resolves at 100ms
p2 resolves at 450ms
p3 resolves at 850ms

When p1 resolves we committed the root boundary (what we commonly refer to as "the shell") 100ms earlier. Since we don't want to reveal more often than every 300ms, we throttle for 200ms and reveal lvl 1 at 300ms.
When p2 resolves at 450ms, lvl1 was revealed 150ms earlier. Since we don't want to reveal more often than every 300ms, we throttle for 150ms and reveal lvl 2 at 600ms.
When p3 resolves at 850ms, lv2 was revealed 250ms earlier. Since we don't want to reveal more often than every 300ms, we throttle for 50ms and reveal lvl 2 at 900ms.

The batching can be observed when you let two boundaries resolve within the same 300ms window e.g.
p1 resolves at 100ms
p2 resolves at 350ms
p3 resolves at 450ms

p1 is throttled for 200ms
p2 is throttled for 250ms
p3 is throttled for 150ms

p2 and p3 are revealed together.

Without throttling all would commit independently within a short timeframe.

Throttling is global so it doesn't just apply to parent-child reveals. Initially, React throttled to 500ms which got reduced to 300ms in React 19. In React 19 we also applied throttling more broadly. The initial version of Suspense revealed boundaries immediately if there were no more nested boundaries.

The other examples are probably self-explanatory. This one could do with an example. Examples for all would be nice with a side-by-side with a Suspense implementation that wouldn't block (e.g. with just some simple DOM operations).

How about with effect as an example? It's a common confusion

That's for use() vs fetching in an Effect though. I was thinking about a boundary with a lot of text. There are sandboxes in the prerender docs (or resume. Can't remember but we do have one example for PPR in the docs) that show how to build sandboxes showing streaming SSR.

Is that clear that this only applies to boundaries that are revealed by new SSR content arriving?